Creating a Payment

There are two types of payments in this system:

• Synchronous Payments: These return a response immediately upon completion.
• Asynchronous Payments: These return a response only after some time, usually because they involve additional processing or offline steps (e.g., UPI, QR code payments, card payments, and direct debit). Most payments fall into the asynchronous category.

Ways to Create a Payment

1. Via a Hosted Checkout Page:
   A single hosted checkout page can handle multiple payments.

   • When a user visits this page, a new payment is created for each available payment method (e.g., a QR code is generated for a PayNow payment).
   • Each payment enters the initiated state, with only one payment progressing to the next state based on the selected payment method.

2. Through API: Initiate Payment Endpoint

   • Call the initiate payment endpoint to initiate a new payment.

3. Through API: Create Payment Endpoint

   • This is the most commonly used method.
   • Call the create payment endpoint to create a new payment.
   • The system places the payment in the initiated state, then processes it to move it into the pending state.

Steps to Create a Payment

To create a payment, use the following API call:

curl --location 'http://localhost:3000/v1/payments' \
--header 'idempotency-key: a43c894e-b6ba-4955-9d86-fc83a636ab1b' \
--header 'Content-Type: application/json' \
--header 'Authorization: {{organisation_secret_key}}' \
--data '{
    "payment_method_code": "sg_dummy_banktransfer",
    "currency": "sgd",
    "amount": 100,
    "details": {
        "banktransfer": {
          // Bank transfer details here
        }
    }
}'

When a payment is created, the following process occurs:

1. The payment request is saved in the database, using a unique idempotency key.
2. Request parameters are gathered (e.g., payment method type, currency, and amount).
3. Based on these parameters, an ordered list of available partners is retrieved from the PartnerPaymentMethod table.
4. The system tries processing the payment with each partner in order of priority.
5. If the payment is successful, the response is stored and returned to the user. The returned status will be either pending or completed.
6. If a payment request fails (e.g., due to partner API issues), the next partner is tried until all options are exhausted.
7. If all partners fail, the payment status is set to failed, and this status is returned to the user.

Available Payment States

Payments can exist in the following states:

• initiated
• pending
• completed
• cancelled
• failed
• partial_refund
• full_refund

Payment State Transition Diagram

The above diagram shows the possible transitions between payment states.

Payment Methods and Partners

Each type of payment is referred to as a payment method (e.g., bank transfer, QR code, UPI, etc.). Each payment method can be fulfilled by one or more partners (software providers, gateways, or banks).

Routing Logic

The selection of a partner for processing a payment is known as routing. Routing is determined based on factors such as:

• Cost: Partner fees and pricing impact the choice.
• Availability: If a partner is currently active and available.
• Performance Factors: Other operational metrics may also influence partner selection.

Relationships

These relationships are represented in the following diagram:

Payment Methods

To maintain simplicity and avoid confusion, all inputs related to payment method types are stored in a single payment transaction object. This structure reduces data bloat and streamlines data processing.

Available payment method types include:

• QR Codes (qrcode)
• Bank Transfers (banktransfer)
• E-Wallets (ewallet)
• Hosted Checkouts (hostedcheckout)